READ_ME_UNFOLDING_PROGRAM.TXT

   Ryan Bakker and Keith T. Poole (ktpoole@uga.edu)

***(CONTACT KEITH POOLE (ktpoole@uga.edu) IF YOU NEED HELP RUNNING THIS
CODE.  UPDATED CODE AND EXAMPLES WILL BE POSTED HERE:

http://voteview.com/Bakker_Poole_Bayesian_MDS.htm

WE WILL EVENTUALLY HAVE PROGRAMS THAT CAN BE RUN FROM WITHIN R WITH A
SIMPLE INTERFACE.  WE PLAN ON HAVING THIS DONE WITHIN 6 MONTHS.)***


1) The unfolding programs that we use in our paper
"Bayesian Metric Multidimensional Scaling" are:

unfolding_automatic_1968.c
unfolding_automatic_2000.c
unfolding_automatic_2004.c

2) The are set up to read the files

thermometers_1968.dat
elec2000_therms.txt
thermometers_2004.txt

respectively.  Each file has the respondent ID number in the first column
followed by the thermometer scores in fixed record format.  The thermometers 
range from 0 - 99 in 1968 and 0 - 100 in 2000 and 2004.  

3) The C program is set up to run on an iMAC OS X computer and it links
in the LAPACK and BLAS libraries from R.  The program also needs the
header files:

lbfgs.h  (Limited memory Broyden-Fletcher_Goldfarb-Shanno header file)
arithmetic_ansi.h (Used by L-BFGS)

4) Place the program, the data file, and the two header files in your working directory; e.g.,

#include </Users/poole/lbfgs.h>

Just search through the code using EMACS and you will see the header declarations.

5) To compile, link, and load, use the command:

gcc -o unfolding_automatic_1968 unfolding_automatic_1968.c -lcblas -lclapack

To run the program you need to have R installed and the GNU Compilers
installed.  Instructions for installing the GNU Compilers are here:

http://voteview.com/measure_Install_RTools.htm

6) The program opens a number of files.  Below are code fragments from
the C program showing these open statements: 

6A)  This File Contains some miscellaneous diagnostic output and it can 
be quite large:

jp =fopen("data_unfolding_1968.txt","w"); 

6B) This File has the slice sampler output for the respondents.  That is, 
all the respondent configurations in the Markov Chain (the first 10,000 
are burn-in -- This is set below with the variable nburn): 

mp = fopen("slice_unfolding_chains_X_1968.txt","w"); 

The file contains the respondent ID number, the starting coordinates, the 
means of the 100,000 trials, and the standard deviations.

6C) This file holds all the estimates of sigma-hat squared:

kp = fopen("slice_unfolding_1968.txt","w");

6D) This File has the slice sampler output for the stimuli:

lp = fopen("slice_unfolding_chains_1968.txt","w");

The 3rd line from the bottom of the file are the means of the 100,000
trials after burn-in.  The 2nd line from the bottom of the file are
the standard deviations.  The last line is the starting coordinates 
for the stimuli.

6E) The Thermometer Data Being Read here:

if((fp =fopen("thermometers_1968.dat","r"))==NULL)

We do a fail-safe check on these dissimilarities with this block of code:

/*
DO TRANSFORMATION TO DISTANCES HERE
*/
  for(i=0;i<nrowX;i++)
  {
	  for(j=0;j<ncolX;j++)
	  {
		  if(XREAD[i*ncolX+j] <= 97)
		  {
			  X[i*ncolX+j] = (100.0-XREAD[i*ncolX+j])/50.0;
		  }
		  if(XREAD[i*ncolX+j] > 97)
		  {
			  X[i*ncolX+j] = -999;
		  }
	  }
  }
Note that this places -999.0 in the vector X[.] for missing data.

7) Below are the key variables that have to be set to read the 
1968 Thermometer matrix.  NS is the number of
dimensions.  N is used in the L-BFGS routine and the formula is:

N=((nrowX+ncolX)*NS)-(NS*(NS+1)/2).  

NDIM is used in the slice sampler and the formula is:

NDIM=(nrowX+ncolX-1)*NS + 1

With unfolding data nrowX > ncolX

Finally, SIGMAPRIOR is the prior on SIGMA-SQUARED for the Log-Normal.

//
#define NS 2                    /*  Number of Dimensions */
#define N 3367  /* 3367 if NS=2, 5049 if NS=3, USED IN L-BFGS ROUTINE -- SET EQUAL to ((nrowX+ncolX)*NS)-3 if NS=2; set equal to ((nrowX+ncolX)*NS) - 6 if NS=3; set equal to ((nrowX+ncolX)*NS) - 10 if NS=4*/
#define NDIM 3369                 /* 3369 if NS=2, 5053 if NS=3 ((nrowX+ncolX)-1)*NS+1  Number of Coordinates Being Estimated + Variance Term*/
#define nrowX 1673                /*   */
#define ncolX 12
#define SIGMAPRIOR 100.0
